3D Graphics Programming with QuickDraw 3D 1.5.4

Vertex Structures

QuickDraw 3D RAVE supports two different types of vertices: Gouraud vertices and texture vertices. You use Gouraud vertices for drawing Gouraud-shaded triangles, and also for drawing points and lines. A Gouraud vertex is defined by the TQAVGouraud data structure, which specifies the position, depth, color, and transparency information.



 
typedef struct TQAVGouraud {

    float                               x;

    float                               y;

    float                               z;

    float                               invW;

    float                               r;

    float                               g;

    float                               b;

    float                               a;

} TQAVGouraud;

x: The x coordinate of the vertex relative to the upper-left corner of the draw context rectangle (that is, the rectangle passed to the QADrawContextNew function). The value of this field is a floating-point value that specifies a number of pixels.
y: The y coordinate of the vertex relative to the upper-left corner of the draw context rectangle (that is, the rectangle passed to the QADrawContextNew function). The value of this field is a floating-point value that specifies a number of pixels.
z: The depth of the vertex. The value of this field is a floating-point number between 0.0 and 1.0 inclusive, where lower numbers specify points closer to the origin.
invW: The inverse w value (that is, the value 1/ w , where w is the homogeneous correction factor). This field is valid only for drawing engines that support the kQAOptional_PerspectiveZ feature. When the state variable kQATag_PerspectiveZ is set to kQAPerspectiveZ_On , hidden surface removal is performed using the value in this field rather than the value in the z field, thereby causing the hidden surface removal to be perspective corrected.
r: The red component of the vertex color.
g: The green component of the vertex color.
b: The blue component of the vertex color.
a: The alpha channel value of the vertex, where 1.0 represents opacity and 0.0 represents complete transparency.

You use texture vertices to define triangles to which a texture is to be mapped. A texture vertex is defined by the TQAVTexture data structure, which specifies the position, depth, transparency, and texture mapping information.

Not all the fields of a TQAVTexture data structure need to be filled out. Many of these fields are used only when texture mapping operations are in force (that is, when the kQATag_TextureOp state variable has some value other than kQATextureOp_None ).



 
typedef struct TQAVTexture {

    float                               x;

    float                               y;

    float                               z;

    float                               invW;

    float                               r;

    float                               g;

    float                               b;

    float                               a;

    float                               uOverW;

    float                               vOverW;

    float                               kd_r;

    float                               kd_g;

    float                               kd_b;

    float                               ks_r;

    float                               ks_g;

    float                               ks_b;

} TQAVTexture;

x: The x coordinate of the vertex relative to the upper-left corner of the draw context rectangle (that is, the rectangle passed to the QADrawContextNew function). The value of this field is a floating-point value that specifies a number of pixels.
y: The y coordinate of the vertex relative to the upper-left corner of the draw context rectangle (that is, the rectangle passed to the QADrawContextNew function). The value of this field is a floating-point value that specifies a number of pixels.
z: The depth of the vertex. The value of this field is a floating-point number between 0.0 and 1.0 inclusive, where lower numbers specify points closer to the origin.
invW: The inverse w value (that is, the value 1/ w , where w is the homogeneous correction factor). This field must contain a value. For drawing engines that support the kQAOptional_PerspectiveZ feature and when the state variable kQATag_PerspectiveZ is set to kQAPerspectiveZ_On , hidden surface removal is performed using the value in this field rather than the value in the z field. For non-perspective rendering, this field should be set to 1.0.
r: The red component of the decal color. The value in this field is used only when the kQATextureOp_Decal texture mapping operation is enabled.
g: The green component of the decal color. The value in this field is used only when the kQATextureOp_Decal texture mapping operation is enabled.
b: The blue component of the decal color. The value in this field is used only when the kQATextureOp_Decal texture mapping operation is enabled.
a: The alpha channel value of the vertex, where 1.0 represents opacity and 0.0 represents complete transparency.
uOverW: The perspective-corrected u coordinate of the vertex.
vOverW: The perspective-corrected v coordinate of the vertex.
kd_r: The red component of the diffuse color of the vertex. The value in this field is used only when the kQATextureOp_Modulate texture mapping operation is enabled. The value in this field can be greater than 1.0 to more accurately render scenes with high light intensities.
kd_g: The green component of the diffuse color of the vertex. The value in this field is used only when the kQATextureOp_Modulate texture mapping operation is enabled. The value in this field can be greater than 1.0 to more accurately render scenes with high light intensities.
kd_b: The blue component of the diffuse color of the vertex. The value in this field is used only when the kQATextureOp_Modulate texture mapping operation is enabled. The value in this field can be greater than 1.0 to more accurately render scenes with high light intensities.
ks_r: The red component of the specular color of the vertex. The value in this field is used only when the kQATextureOp_Highlight texture mapping operation is enabled.
ks_g: The green component of the specular color of the vertex. The value in this field is used only when the kQATextureOp_Highlight texture mapping operation is enabled.
ks_b: The blue component of the specular color of the vertex. The value in this field is used only when the kQATextureOp_Highlight texture mapping operation is enabled.

A drawing engine may choose to use a single modulation value instead of the three values kd_r , kd_g , and kd_b . This change is transparent to applications, except that colored lights applied to a texture appear white. As a result, a drawing engine that uses this simplification must negate the kQAOptional_TextureColor bit in the optional features value returned by QAEngineGestalt . Similarly, a drawing engine may choose to use a single highlight value instead of the three values ks_r , ks_g , and ks_b . This change is transparent to applications, except that a texture-mapped object's specular highlight appears white, not colored. As a result, a drawing engine that uses this simplification must negate the kQAOptional_TextureColor bit in the optional features value.